.TH int6ktest 1 "November 2013" "open-plc-utils-0.0.3" "Qualcomm Atheros Open Powerline Toolkit"

.SH NAME
int6ktest - Qualcomm Atheros Test Applet Loader

.SH SYNOPSIS
.BR int6ktest
.RI [ options ] 
.RI [ file ] 
.RI [ file ] 
[...]

.SH DESCRIPTION
Download and execute one or more test applets on the local powerline device.
An applet is a small firmware image that can be started by the bootloader and that returns to the bootloader when done.

.PP
An Atheros image file can contain one or more firmware images.
Each image is preceded by a header that specifies the image size, load address and start address.
\fBint6ktest\fR sequentially dowloads and executes each image found in each image file specified as a command line argument.
It waits for each image to complete before it will download and execute the next image.
The program terminates once all images in all image files have been executed or some image fails to complete within 60 seconds.

.PP
Most applets return to the Bootloader on successful completion so that another applet can be downloaded and executed.
This allows applet chains to be executed using one command.
A chain may consist of one image file containing many applets or several image files containing one applet each or any combination.
The chain will break, after a timeout, if any applet in the chain fails to return to the Bootloader.

.PP
The toolkit contains a set of useful applets in folder \fBapplets\fR.
Most, if not all, are as single applet image files.
Program \fBchknvm\fR can be used to inspect image files and programs \fBnvmmerge\fR and \fBnvmsplit\fR can be used to assemble and disassemble multi-applet image files.
This allows custom applet chains to be created and kept together in one file.
The number and quality of available applets will probably increase with time.

.PP
Users should take the time to understand the applets they attempt to execute or confusion may result.
Each applet should have an associated man page to explain what it does and how it works.
Most applets execute and return to the bootloader within seconds but some loop indefinitely or stop on failure.
Newer applets print test progress and outcomes on the console but older applets merely flash device LEDs to indicate test progress and outcomes.

.PP
This program is part of the Qualcomm Atheros Powerline Toolkit.
See the \fBplc\fR man page for an overview and installation instructions.

.SH COMMENTS
This program is an alternative to program \fBamptest\fR but is deprecated.
In the future, applet designers should develop applets for \fBamptest\fR instead of this program.

.SH OPTIONS

.TP
-\fBc \fIcount\fR
The number of times the program will poll the device before declaring an event failure.
The program will wait a fixed period of time between each poll attempt.
Overall wait time is \fBcount/frequency\fR where count can be modified using option \fB-c\fR.
Overall wait time is always approximate since operating system overhead and latency are not taken into account.
The default count is \fB60\fR.

.TP
.RB - e
Redirects stderr messages to stdout.
By convention status and error messages are printed on stderr while primary program output is printed on stdout.
This option prints all output on stdout in cases where this is desired.

.TP
-\fBi\fR \fIinterface\fR
Select the host Ethernet interface.
All requests are sent via this host interface and only reponses received via this host interface are recognized.
The default interface is \fBeth1\fR because most people use \fBeth0\fR as their principle network connection; however, if environment string "PLC" is defined then it takes precedence over the default interface.
This option then takes precedence over either default.

.TP
.RB - l
Sequentially execute and re-execute all applets in all files on the command line until the program is terminated with \fB^C\fR.

.TP
-\fBp \fIfrequency\fR
The polling frequency expressed in polls-per-second.
For example, 1 means one poll per second and 10 means ten polls per second.
Overall wait time is \fBcount/frequency\fR where count may be modified using option \fB-c\fR.
Overall wait time is always approximate since operating system overhead and latency are not taken into account.
The default frequency is \fB5\fR.

.TP
.RB - q
Suppresses normal progress and status messages.

.TP
-\fBt \fImilliseconds\fR
Read timeout in milliseconds.
Values range from 0 through UINT_MAX.
This is the maximum time allowed for a response.
The default is shown in brackets on the program menu.

.TP
.RB - v
Print additional information on stdout.
Specifically, this option prints incoming and outgoing frames in hexadecimal format on stdout.
Output can be directed to a text file for analysis.

.TP
.RB - x
Cause the program to exit on the first error instead of moving on to the next applet.
Error exits return a non-zero value to the shell.

.TP
-\fB?\fR, --\fBhelp\fR
Print program help summary on stdout.
This option takes precedence over other options on the command line.

.TP
-\fB!\fR, --\fBversion\fR
Print program version information on stdout.
This option takes precedence over other options on the command line.
Use this option when sending screen dumps to Atheros Technical Support so that they know exactly which version of the Linux Toolkit you are using.

.SH ARGUMENTS

.TP
\fIfile\fR
The name of an Atheros image file.
The image file may contain one or more images.
Each image will be downloaded and executed in turn until all images are executed or an image fails to return the device to the Bootloader within 1 hour for some reason.

.SH EXAMPLES
The following example sequentially downloads then executes each image in file \fBabc.nvm\fR in turn.
Each image must complete and return to the bootloader before the next one downloads.
Observe that no device address is needed because Atheros powerline devices all use address 00:b0:52:00:00:01 when in bootloader mode.

.PP
   # int6ktest abc.nvm

.PP
The following example will sequentially download and execute the images in each file \fBabc.nvm\fR, \fBdef.nvm\fR and \fBghi.nvm\fR in turn.

.PP
   # int6ktest abc.nvm def.nvm ghi.nvm

.SH DISCLAIMER
Atheros image file structure and content is proprietary to Qualcomm Atheros, Ocala FL USA.
Consequently, public information is not available.
Qualcomm Atheros reserves the right to change file structure or content in future firmware releases without any obligation to notify or compensate users of this program.
This program is reserved for use by Atheros Field Engineers.
Use of this program may void some contractual obligations made by Atheros.

.SH SEE ALSO
.BR chknvm ( 1 ),
.BR chknvm2 ( 1 ),
.BR amptest ( 1 ),
.BR nvmsplit ( 1 ),
.BR nvmmerge ( 1 ),
.BR plctest ( 1 ),
.BR setnvm ( 1 )

.SH CREDITS
 Charles Maier

